add documentation for MS Graph plugin #130703

richard-dennehy · 2025-07-07T09:49:46Z

Add documentation for the plugin introduced in #128396

This will need a manual backport to 8.19

github-actions · 2025-07-07T09:49:54Z

🔍 Preview links for changed docs:

🔔 The preview site may take up to 3 minutes to finish building. These links will become live once it completes.

github-actions · 2025-07-07T09:58:24Z

🔍 Preview links for changed docs

elasticsearchmachine · 2025-07-08T08:33:03Z

Pinging @elastic/es-docs (Team:Docs)

elasticsearchmachine · 2025-07-08T08:33:03Z

Pinging @elastic/es-security (Team:Security)

docs/reference/elasticsearch-plugins/ms-graph-authz.md

shainaraskas

a few suggestions

docs/reference/elasticsearch-plugins/authentication-plugins.md

docs/reference/elasticsearch-plugins/ms-graph-authz.md

shainaraskas · 2025-07-08T16:16:52Z

docs/reference/elasticsearch-plugins/ms-graph-authz.md

+This plugin can be installed using the plugin manager:
+
+```sh
+sudo bin/elasticsearch-plugin install microsoft-graph-authz
+```


does this plugin work for all deployment types, or just self-managed vanilla elasticsearch?

I've been testing with Elastic Cloud, but it should work with any other deployment type

in ecloud, I assume you can't install this way (with a sudo command).

consider linking to https://www.elastic.co/docs/reference/elasticsearch/plugins/plugin-management which explains how to install plugins in all environments.

you could say something like this near the end of the section

If you're using a [self-managed Elasticsearch cluster](docs-content:///deploy-manage/deploy/self-managed.md), then this plugin can be installed using the plugin manager: <code> For all other deployment types, refer to [](../plugin-management.md).

docs/reference/elasticsearch-plugins/authentication-plugins.md

docs/reference/elasticsearch-plugins/ms-graph-authz-configure-azure.md

shainaraskas · 2025-07-08T16:21:59Z

docs/reference/elasticsearch-plugins/ms-graph-authz-configure-azure.md

+    :alt: get your application ID
+    :::
+4) Under Manage > Certificates & secrets
+   - Create a new client secret


Suggested change

- Create a new client secret

- Create a new client secret.

shainaraskas · 2025-07-08T16:26:24Z

docs/reference/elasticsearch-plugins/ms-graph-authz-configure-azure.md

+5) Under Manage > API permissions
+   - Go to “Add a permission”
+   - Choose “Microsoft Graph”
+   - Choose “Application permissions”
+   - Select “Directory.ReadWrite.All, Group.ReadWrite.All, User.Read.All”
+   - Note that an Azure Admin will need to approve these permissions before the credentials can be used
+     :::{image} ./images/ms-graph-authz/05-configure-api-permissions.png
+     :alt: configure api permissions
+     :::


ordered procedures of more than two items need a numbered list

Suggested change

5) Under Manage > API permissions

- Go to “Add a permission”

- Choose “Microsoft Graph”

- Choose “Application permissions”

- Select “Directory.ReadWrite.All, Group.ReadWrite.All, User.Read.All”

- Note that an Azure Admin will need to approve these permissions before the credentials can be used

:::{image} ./images/ms-graph-authz/05-configure-api-permissions.png

:alt: configure api permissions

:::

5) Under **Manage** > **API permissions**, do the following:

1. Go to **Add a permission**.

2. Choose **Microsoft Graph**.

3. Choose **Application permissions**.

4. Select the following permissions: `Directory.ReadWrite.All`, `Group.ReadWrite.All`, and `User.Read.All`.

Note that an Azure Admin will need to approve these permissions before the credentials can be used

:::{image} ./images/ms-graph-authz/05-configure-api-permissions.png

:alt: configure API permissions

:::

docs/reference/elasticsearch-plugins/ms-graph-authz-configure-elasticsearch.md

shainaraskas · 2025-07-08T16:28:24Z

docs/reference/elasticsearch-plugins/ms-graph-authz-configure-elasticsearch.md

+
+Create a Microsoft Graph realm, following the above settings, then configure an existing realm to delegate to it using `authorization_realms`.
+
+For example, to authenticate via Microsoft Entra with SAML and use the Microsoft Graph plugin to look up group membership:


Suggested change

For example, to authenticate via Microsoft Entra with SAML and use the Microsoft Graph plugin to look up group membership:

For example, the following configuration authenticates using Microsoft Entra with SAML, and uses the Microsoft Graph plugin to look up group membership:

shainaraskas

Provided some small additional pieces of feedback.

The only things I'd consider to be blocking are:

explaining how to set up the graph plugin on other deployment types because they won't accept a sudo command anywhere
linking down to the config topics from the parent authz topic :)

approving to unblock but suggest taking a look at these items if you can.

Also wonder if these settings will get added to the core elasticsearch reference or just here.

shainaraskas · 2025-08-27T14:37:22Z

docs/reference/elasticsearch-plugins/authentication-plugins.md

+  stack: ga 9.1
+---
+
+# Authentication Plugins [authentication]


Suggested change

# Authentication Plugins [authentication]

# Authentication plugins [authentication]

shainaraskas · 2025-08-27T14:40:07Z

docs/reference/elasticsearch-plugins/ms-graph-authz.md

+  stack: ga 9.1
+---
+
+# Microsoft Graph Authz [ms-graph-authz]


would be good if this page would call down to the two child pages, e.g. in a new Configuration H2 on this page, just saying "To learn how to configure the Microsoft Graph Authz plugin, refer to ."

or something similar.

otherwise, it's unclear that there are configs needed unless you're looking at the sidebar.

shainaraskas · 2025-08-27T14:44:35Z

docs/reference/elasticsearch-plugins/ms-graph-authz.md

+This plugin can be installed using the plugin manager:
+
+```sh
+sudo bin/elasticsearch-plugin install microsoft-graph-authz
+```


in ecloud, I assume you can't install this way (with a sudo command).

consider linking to https://www.elastic.co/docs/reference/elasticsearch/plugins/plugin-management which explains how to install plugins in all environments.

you could say something like this near the end of the section

If you're using a [self-managed Elasticsearch cluster](docs-content:///deploy-manage/deploy/self-managed.md), then this plugin can be installed using the plugin manager: <code> For all other deployment types, refer to [](../plugin-management.md).

shainaraskas · 2025-08-27T16:03:51Z

docs/reference/elasticsearch-plugins/ms-graph-authz-configure-azure.md

+To make API calls to Microsoft Graph, Elasticsearch requires Azure credentials
+with the correct permissions.
+
+## Create a custom Azure Application


Suggested change

## Create a custom Azure Application

## Create a custom Azure application

shainaraskas · 2025-08-27T16:04:12Z

docs/reference/elasticsearch-plugins/ms-graph-authz-configure-azure.md

+    4. Select `Directory.ReadWrite.All`, `Group.ReadWrite.All`, `User.Read.All`.
+
+   Note that an Azure Admin will need to approve these permissions before the
+   credentials can be used


Suggested change

credentials can be used

credentials can be used.

:::

shainaraskas · 2025-08-27T16:04:29Z

docs/reference/elasticsearch-plugins/ms-graph-authz-configure-azure.md

+    3. Choose **Application permissions**.
+    4. Select `Directory.ReadWrite.All`, `Group.ReadWrite.All`, `User.Read.All`.
+
+   Note that an Azure Admin will need to approve these permissions before the


Suggested change

Note that an Azure Admin will need to approve these permissions before the

:::{note}

An Azure Admin must approve these permissions before the

shainaraskas · 2025-08-27T16:06:34Z

docs/reference/elasticsearch-plugins/ms-graph-authz-configure-elasticsearch.md

+
+# Configuration properties [configuration-properties]
+
+After the plugin is installed, the following configuration settings are


consider flipping this page around. explain how to configure, and then create an ## Available settings section with the full setting reference.

elasticsearchmachine · 2025-08-28T14:00:20Z

Pinging @elastic/core-docs (Team:Docs)

richard-dennehy added >docs General docs changes :Security/Authentication Logging in, Usernames/passwords, Realms (Native/LDAP/AD/SAML/PKI/etc) Team:Security Meta label for security team labels Jul 7, 2025

elasticsearchmachine added the v9.2.0 label Jul 7, 2025

richard-dennehy force-pushed the ms-graph-docs branch from 8836670 to e884907 Compare July 7, 2025 09:53

add documentation for MS Graph plugin

1a01d28

richard-dennehy force-pushed the ms-graph-docs branch from e884907 to 1a01d28 Compare July 7, 2025 09:57

richard-dennehy force-pushed the ms-graph-docs branch 3 times, most recently from a8599c7 to c26b3c1 Compare July 7, 2025 13:59

add clarifying screenshots

425099e

richard-dennehy force-pushed the ms-graph-docs branch from c26b3c1 to 425099e Compare July 7, 2025 14:51

richard-dennehy added the v9.1.1 label Jul 8, 2025

richard-dennehy marked this pull request as ready for review July 8, 2025 08:32

elasticsearchmachine added the Team:Docs Meta label for docs team label Jul 8, 2025

richard-dennehy commented Jul 8, 2025

View reviewed changes

docs/reference/elasticsearch-plugins/ms-graph-authz.md Outdated Show resolved Hide resolved

use docs-content link for internal docs reference

243e5a1

richard-dennehy force-pushed the ms-graph-docs branch from 88b47fd to 243e5a1 Compare July 8, 2025 10:15

richard-dennehy mentioned this pull request Jul 8, 2025

backport ms graph plugin docs to 8.19 #130823

Merged

shainaraskas reviewed Jul 8, 2025

View reviewed changes

richard-dennehy added 4 commits July 9, 2025 10:46

address review comments

d7d6a90

Merge branch 'main' into ms-graph-docs

40645be

fix formatting issue

a6abff1

adjust formatting

3583699

elasticsearchmachine added v9.1.2 and removed v9.1.1 labels Aug 6, 2025

Merge branch 'main' into ms-graph-docs

914ab9b

richard-dennehy force-pushed the ms-graph-docs branch from e1d3a15 to 8efd005 Compare August 8, 2025 13:32

fix version in template expression

6f0bf3e

richard-dennehy force-pushed the ms-graph-docs branch from 8efd005 to 6f0bf3e Compare August 8, 2025 13:43

elasticsearchmachine added v9.1.3 and removed v9.1.2 labels Aug 11, 2025

Merge branch 'main' into ms-graph-docs

7d13d02

elasticsearchmachine added v9.1.4 and removed v9.1.3 labels Aug 21, 2025

mattc58 requested a review from shainaraskas August 21, 2025 13:15

shainaraskas approved these changes Aug 27, 2025

View reviewed changes

address review comments

4157d99

richard-dennehy added 3 commits August 28, 2025 15:14

Merge branch 'main' into ms-graph-docs

09d01f6

fix unterminated note

ed11992

minor configuration example fix

8551266

richard-dennehy enabled auto-merge (squash) August 28, 2025 14:21

richard-dennehy merged commit 37f65b0 into elastic:main Aug 28, 2025
10 checks passed


		Create a Microsoft Graph realm, following the above settings, then configure an existing realm to delegate to it using `authorization_realms`.

		For example, to authenticate via Microsoft Entra with SAML and use the Microsoft Graph plugin to look up group membership:

	For example, to authenticate via Microsoft Entra with SAML and use the Microsoft Graph plugin to look up group membership:
	For example, the following configuration authenticates using Microsoft Entra with SAML, and uses the Microsoft Graph plugin to look up group membership:

	# Authentication Plugins [authentication]
	# Authentication plugins [authentication]

	## Create a custom Azure Application
	## Create a custom Azure application

	Note that an Azure Admin will need to approve these permissions before the
	:::{note}
	An Azure Admin must approve these permissions before the


		# Configuration properties [configuration-properties]

		After the plugin is installed, the following configuration settings are

add documentation for MS Graph plugin #130703

add documentation for MS Graph plugin #130703

Uh oh!

Conversation

richard-dennehy commented Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

elasticsearchmachine commented Jul 8, 2025

Uh oh!

elasticsearchmachine commented Jul 8, 2025

Uh oh!

Uh oh!

shainaraskas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shainaraskas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elasticsearchmachine commented Aug 28, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

richard-dennehy commented Jul 7, 2025 •

edited

Loading

github-actions bot commented Jul 7, 2025 •

edited

Loading

github-actions bot commented Jul 7, 2025 •

edited

Loading